---
title: PasswordProvider
editUrl: https://github.com/toolbeam/openauth/blob/master/packages/openauth/src/provider/password.ts
description: Reference doc for the `PasswordProvider`.
---

import { Segment, Section, NestedTitle, InlineSection } from 'toolbeam-docs-theme/components'
import { Tabs, TabItem } from '@astrojs/starlight/components'

<div class="tsdoc">
<Section type="about">
Configures a provider that supports username and password authentication. This is usually
paired with the `PasswordUI`.

```ts
import { PasswordUI } from "@openauthjs/openauth/ui/password"
import { PasswordProvider } from "@openauthjs/openauth/provider/password"

export default issuer({
  providers: {
    password: PasswordProvider(
      PasswordUI({
        copy: {
          error_email_taken: "This email is already taken."
        },
        sendCode: (email, code) => console.log(email, code)
      })
    )
  },
  // ...
})
```

Behind the scenes, the `PasswordProvider` expects callbacks that implements request handlers
that generate the UI for the following.

```ts
PasswordProvider({
  // ...
  login: (req, form, error) => Promise<Response>
  register: (req, state, form, error) => Promise<Response>
  change: (req, state, form, error) => Promise<Response>
})
```

This allows you to create your own UI for each of these screens.
</Section>
---
## Methods
### PasswordProvider
<Segment>
<Section type="signature">
```ts
PasswordProvider(config)
```
</Section>
<Section type="parameters">
#### Parameters
- <p><code class="key">config</code> [<code class="type">PasswordConfig</code>](/docs/provider/password#passwordconfig)</p>
</Section>
<InlineSection>
**Returns** <code class="type">Provider</code>
</InlineSection>
</Segment>
## PasswordChangeError
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_email</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_code</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_password</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">password_mismatch</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">message</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">validation_error</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code>
</InlineSection>
</Section>
The errors that can happen on the change password screen.

| Error | Description |
| ----- | ----------- |
| `invalid_email` | The email is invalid. |
| `invalid_code` | The code is invalid. |
| `invalid_password` | The password is invalid. |
| `password_mismatch` | The passwords do not match. |
</Segment>
## PasswordChangeState
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="symbol">&lcub; </code><code class="key">redirect</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">start</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">code</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">email</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">redirect</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">code</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">email</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">redirect</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">update</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code>
</InlineSection>
</Section>
The state of the password change flow.

| State | Description |
| ----- | ----------- |
| `start` | The user is asked to enter their email address to start the flow. |
| `code` | The user needs to enter the pin code to verify their email. |
| `update` | The user is asked to enter their new password and confirm it. |
</Segment>
## PasswordConfig
<Segment>
<Section type="parameters">
- <p>[<code class="key">change</code>](#passwordconfig.change) <code class="primitive">(req: <code class="type">Request</code>, state: [<code class="type">PasswordChangeState</code>](/docs/provider/password#passwordchangestate), form?: <code class="type">FormData</code>, error?: [<code class="type">PasswordChangeError</code>](/docs/provider/password#passwordchangeerror)) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="type">Response</code><code class="symbol">&gt;</code></code></p>
- <p>[<code class="key">login</code>](#passwordconfig.login) <code class="primitive">(req: <code class="type">Request</code>, form?: <code class="type">FormData</code>, error?: [<code class="type">PasswordLoginError</code>](/docs/provider/password#passwordloginerror)) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="type">Response</code><code class="symbol">&gt;</code></code></p>
- <p>[<code class="key">register</code>](#passwordconfig.register) <code class="primitive">(req: <code class="type">Request</code>, state: [<code class="type">PasswordRegisterState</code>](/docs/provider/password#passwordregisterstate), form?: <code class="type">FormData</code>, error?: [<code class="type">PasswordRegisterError</code>](/docs/provider/password#passwordregistererror)) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="type">Response</code><code class="symbol">&gt;</code></code></p>
- <p>[<code class="key">sendCode</code>](#passwordconfig.sendcode) <code class="primitive">(email: <code class="primitive">string</code>, code: <code class="primitive">string</code>) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="primitive">void</code><code class="symbol">&gt;</code></code></p>
- <p>[<code class="key">validatePassword?</code>](#passwordconfig.validatepassword) [<code class="type">StandardSchema</code>](https://github.com/standard-schema/standard-schema)<code class="symbol"> | </code><code class="primitive">(password: <code class="primitive">string</code>) => <code class="primitive">undefined</code><code class="symbol"> | </code><code class="primitive">string</code><code class="symbol"> | </code><code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="primitive">undefined</code><code class="symbol"> | </code><code class="primitive">string</code><code class="symbol">&gt;</code></code></p>
</Section>
</Segment>
<NestedTitle id="passwordconfig.change" Tag="h4" parent="PasswordConfig.">change</NestedTitle>
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="primitive">(req: <code class="type">Request</code>, state: [<code class="type">PasswordChangeState</code>](/docs/provider/password#passwordchangestate), form?: <code class="type">FormData</code>, error?: [<code class="type">PasswordChangeError</code>](/docs/provider/password#passwordchangeerror)) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="type">Response</code><code class="symbol">&gt;</code></code>
</InlineSection>
</Section>
The request handler to generate the UI for the change password screen.

Takes the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
and optionally [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
ojects.

Also passes in the current `state` of the flow and any `error` that occurred.

Expects the [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object
in return.
</Segment>
<NestedTitle id="passwordconfig.login" Tag="h4" parent="PasswordConfig.">login</NestedTitle>
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="primitive">(req: <code class="type">Request</code>, form?: <code class="type">FormData</code>, error?: [<code class="type">PasswordLoginError</code>](/docs/provider/password#passwordloginerror)) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="type">Response</code><code class="symbol">&gt;</code></code>
</InlineSection>
</Section>
The request handler to generate the UI for the login screen.

Takes the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
and optionally [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
ojects.

In case of an error, this is called again with the `error`.

Expects the [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object
in return.
</Segment>
<NestedTitle id="passwordconfig.register" Tag="h4" parent="PasswordConfig.">register</NestedTitle>
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="primitive">(req: <code class="type">Request</code>, state: [<code class="type">PasswordRegisterState</code>](/docs/provider/password#passwordregisterstate), form?: <code class="type">FormData</code>, error?: [<code class="type">PasswordRegisterError</code>](/docs/provider/password#passwordregistererror)) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="type">Response</code><code class="symbol">&gt;</code></code>
</InlineSection>
</Section>
The request handler to generate the UI for the register screen.

Takes the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
and optionally [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
ojects.

Also passes in the current `state` of the flow and any `error` that occurred.

Expects the [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object
in return.
</Segment>
<NestedTitle id="passwordconfig.sendcode" Tag="h4" parent="PasswordConfig.">sendCode</NestedTitle>
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="primitive">(email: <code class="primitive">string</code>, code: <code class="primitive">string</code>) => <code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="primitive">void</code><code class="symbol">&gt;</code></code>
</InlineSection>
</Section>
Callback to send the confirmation pin code to the user.
```ts
{
  sendCode: async (email, code) => {
    // Send an email with the code
  }
}
```
</Segment>
<NestedTitle id="passwordconfig.validatepassword" Tag="h4" parent="PasswordConfig.">validatePassword?</NestedTitle>
<Segment>
<Section type="parameters">
<InlineSection>
**Type** [<code class="type">StandardSchema</code>](https://github.com/standard-schema/standard-schema)<code class="symbol"> | </code><code class="primitive">(password: <code class="primitive">string</code>) => <code class="primitive">undefined</code><code class="symbol"> | </code><code class="primitive">string</code><code class="symbol"> | </code><code class="primitive">Promise</code><code class="symbol">&lt;</code><code class="primitive">undefined</code><code class="symbol"> | </code><code class="primitive">string</code><code class="symbol">&gt;</code></code>
</InlineSection>
</Section>
Callback to validate the password on sign up and password reset.
```ts
{
  validatePassword: (password) => {
     return password.length < 8 ? "Password must be at least 8 characters" : undefined
  }
}
```
</Segment>
## PasswordLoginError
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_password</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_email</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code>
</InlineSection>
</Section>
The errors that can happen on the login screen.

| Error | Description |
| ----- | ----------- |
| `invalid_email` | The email is invalid. |
| `invalid_password` | The password is invalid. |
</Segment>
## PasswordRegisterError
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_code</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">email_taken</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_email</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">invalid_password</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">password_mismatch</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">message</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">validation_error</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code>
</InlineSection>
</Section>
The errors that can happen on the register screen.

| Error | Description |
| ----- | ----------- |
| `email_taken` | The email is already taken. |
| `invalid_email` | The email is invalid. |
| `invalid_code` | The code is invalid. |
| `invalid_password` | The password is invalid. |
| `password_mismatch` | The passwords do not match. |
</Segment>
## PasswordRegisterState
<Segment>
<Section type="parameters">
<InlineSection>
**Type** <code class="symbol">&lcub; </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">start</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code><code class="symbol"> | </code><code class="symbol">&lcub; </code><code class="key">code</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">email</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">password</code><code class="symbol">&colon; </code><code class="primitive">string</code><code class="symbol">, </code><code class="key">type</code><code class="symbol">&colon; </code><code class="symbol">&ldquo;</code><code class="primitive">code</code><code class="symbol">&rdquo;</code><code class="symbol"> &rcub;</code>
</InlineSection>
</Section>
The states that can happen on the register screen.

| State | Description |
| ----- | ----------- |
| `start` | The user is asked to enter their email address and password to start the flow. |
| `code` | The user needs to enter the pin code to verify their email. |
</Segment>
</div>